\cvsection{编译使用详解}
在本章节里，我会用很短的篇幅快速介绍一下与{\dk}运行相关的内容，包括本地环境准备、Makefile及编译、选项设定和使用流程，有些内容比较重要，请尽量顺序阅读。

\cvsubsection{本地环境准备}
在真正开始使用{\dk}进行创作之前，要先准备好你的本地编译环境。

\cvsubsubsection{关于兼容性}
我是使用TexLive 2022套件在Ubuntu 20.04平台上对{\dk}进行开发维护和编译测试的，如果你的是Windows操作系统，或其他版本TeX套件，可能会遇到问题，虽然{\dk}的Makefile已经针对Windows系统进行了设计，但对应Windows版本的TexLive套件，以及GNU Make和Python 3可能需要你花些功夫安装调试一番。目前还没有更加详细的测试结果，也衷心希望能够得到你的使用情况反馈。

\cvsubsubsection{关于字体}
由于{\dk}主要使用$ctex$宏包进行中文环境底层支持，而$ctex$默认提供的四套不同平台的字体方案都比较通用，没有个性化的设置，并且{\dk}在$ctex$的基础上增加了几个中文环境下的常用字体，因此需要采用custom方式进行设置，配置文件的相对位置在：\dkbutton{./src/ctex-fontset-custom.def}

完整列表如下：

\begin{cvhonors}*[LLL]
  \cvhonor
  {\heiti\color{black}字体名称}
  {\heiti\color{black}说明}
  {\heiti\color{black}短命令}
  \cvhonor
  {Adobe 仿宋 Std}
  {文档正文默认字体，大小为10pt}
  {\textbackslash fangsong}
  \cvhonor
  {Adobe 黑体 Std}
  {\heiti 一般用于章节名称}
  {\textbackslash heiti}
  \cvhonor
  {Adobe 楷体 Std}
  {\kaishu 脚注、代码块以及中文Mono/Sans环境会用到}
  {\textbackslash kaishu}
  \cvhonor
  {方正小标宋简体}
  {\fzxbs 主要用于章节标题等场景}
  {\textbackslash fzxbs}
  \cvhonor
  {Inconsolata}
  {\sffamily Footnote, Code block and English Mono/Sans Environmet}
  {\textbackslash sffamily}
  \cvhonor
  {Adobe 宋体 Std}
  {\songti 在文档中几乎不用，可以根据需要使用}
  {\textbackslash songti}
  \cvhonor
  {幼圆}
  {\youyuan 艺术创意等场景可能会用到}
  {\textbackslash youyuan}
  \cvhonor
  {隶书}
  {\lishu 诗词歌赋、文学环境比较合适}
  {\textbackslash lishu}
\end{cvhonors}

以上字体一部分是{\dk}基本依赖，一部分是本文档所用字体，建议全部安装，或者根据需要自行修改字体配置文件。短命令的具体用法可以参考本文档源码。

\cvsubsubsection{参考配置}
因为本地环境的构建可以有很多种选择，现在以我的配置为例：

\begin{enumerate}
  \item Ubuntu 20.04
  \item TexLive 2022
  \item GNU Make 4.2.1
  \item Python 3.8.10
  \item Python Pygments
\end{enumerate}

如果你用的是Linux操作系统，很有可能已经自带GNU Make和Python了，使用下面的命令查看一下版本号，确保版本别太旧：

\begin{dkcode}*{bash}
# 这里推荐使用Python3
pytho3 --version

# 查看GNU Make版本，越高越好
make --version
\end{dkcode}

之所以需要Python支持，是因为{\dk}部分组件使用了$minted$引擎调用$Pygments$库进行代码高亮渲染，如果缺少该库，这部分组件将不可用：

\begin{dkcode}*{bash}
# 查看Pygments版本
pygmentize -V

# 安装或升级Pygments库
pip install --upgrade Pygments
\end{dkcode}

\cvsubsection{Makefile及编译}
{\dk}使用Makefile\footnote{前半部分的指令都有注释进行说明，GNU Make的用法也不在本文的讨论范围之内，感兴趣的朋友可以自行学习。}将几个最常用的{\LaTeX}编译相关操作定义成了对应的控制台命令，用以对编译、输出、清理等过程进行简化处理，以及联动resource文件夹下的Makefile文件。

\dkcodefile*{../Makefile}{makefile}[Makefile]

\begin{dkcomment}
  以下所有make命令，都必须在项目根目录（就是你能看到README.md的地方）下执行。
\end{dkcomment}

\begin{cvhonors}*
  \cvhonor
  {make}
  {自动编译输出main.tex，等同于make main}
  {编译输出}
  \cvhonor
  {make main}
  {同上}
  {编译输出}
  \cvhonor
  {make doc}
  {自动编译输出{\dk}文档，也就是本文档的输出命令}
  {编译输出}
  \cvhonor
  {make resource}
  {使用resource文件夹下的Makefile编译输出所有支持的资源文件，等同于进入resource文件夹下进行make或make all}
  {关联编译}
  \cvhonor
  {make all}
  {一次性编译main.tex和{\dk}文档，等同于make main \&\& make doc}
  {编译输出}
  \cvhonor
  {make dist}
  {主要用于执行{\dk}本身发布前的准备工作：新建doc目录，生成文档及清理，普通使用者用不到该命令}
  {项目维护}
  \cvhonor
  {make clean}
  {自动清理所有临时文件和文件夹，包括主目录和所有子目录}
  {自动清理}
  \cvhonor
  {make cleanall}
  {在自动清理所有临时文件和文件夹的基础上，还会删除掉所有主目录下的PDF文件，并联动resource文件夹下所有生成的资源PDF}
  {自动清理}
\end{cvhonors}

\begin{dkcomment}
  make cleanall只会删除符合资源文件命名规则的PDF文件，其他文件不受影响。
\end{dkcomment}

\cvsubsection{文档选项及设定}
{\dk}提供了用于立刻开始创作的初始文件，位置是src/main.tex，该文件导言区\footnote{相信你知道什么是导言区，如果不是太清楚，还是抓紧自学一下吧，或者简单的认为，在大多数情况下，\\\textbackslash begin\{document\}前面的部分，就是导言区。}部分的设定与本文档源码src/dukang-doc.tex完全相同，只需要根据需要修改一些文档名称、作者姓名、首页需要哪些字段、是否需要首行缩进等信息和选项，就可以正式开始为你的大作添加正文了。

打开main.tex之后，首先会看到导言区一堆设定和备注信息，大多数情况下，阅读这些备注信息就足够掌握如何修改了，这里对所有选项进行深入说明。

\begin{cventries}
\cventry
[\Verb{\documentclass[12pt, a4paper, final]{awesome-cv-dukang}}]
[基本配置]
{
  \item 正式引入Awesome-CV文档类。
  \item 这里的字号设定（12pt）基本没什么卵用，因为几乎每个文档组件都定义了自己的字体风格。
}
\cventry
[\Verb{\geometry{left=1.4cm, top=.8cm, right=1.4cm, bottom=1.8cm, footskip=14.5pt}}]
[基本配置]
{
  \item 使用geometry宏包定义纸张的页边距以及页脚距离
}
\cventry
[\Verb{\colorlet{awesome}{awesome-red}}]
[Awesome-CV]
[Awesome-CV的颜色设定]
[必选]
{
  \item 可以指定Awesome-CV预制好的几个配色集，包括awesome-emerald, awesome-skyblue, awesome-red, awesome-pink, awesome-orange, awesome-nephritis, awesome-concrete, awesome-darknight
  \item 也可以使用\Verb{\definecolor}指定自己喜欢的颜色，总共有awesome, darktext, text, graytext, lighttext, sectiondivider这几个颜色名称可供定义。
  \item {\color{awesome}{\dk}提供的所有增强组件都可以根据颜色设定进行风格自适应哦\faKissWinkHeart}
}
\cventry
[\Verb{\setbool{acvSectionColorHighlight}{true}}]
[Awesome-CV]
[指定是否使用配色凸显章节标题后紧跟的分割线]
[必选]
{
  \item 如果设定为true，责章节名称后面的长分割线会有颜色，否则为黑色。
}
\cventry
[\Verb{\renewcommand{\acvHeaderSocialSep}{\quad\textbar\quad}}]
[Awesome-CV]
[封面头部Logo右侧社交媒体帐号之间的分隔符定义]
[可选]
{
  \item 默认为管道符：\dkbutton{<空格>\textbar <空格>}
}
\cventry[个人信息部分][Awesome-CV][该部分用来定义一些个人信息或文档信息][部分可选]
{
  \item \Verb{\photo[rectangle,noedge,left]{./src/resource/dukang-logo}}用于定义首页的Logo图片，文件扩展名默认为.png，可用的裁剪选项为circle（圆形）和rectangle（正方形），可用的边框选项为edge（有边框）和noedge（无边框），可用的位置选项为left（靠左）和right（靠右）。
  \item 该部分除了\Verb{\name}和\Verb{\dukangPDFTitle}是必选的以外，其他设定不需要的均可以注释掉，首页中相应的部分会自适应。
  \item {\color{awesome}由于\Verb{\name}在Awesome-CV文档类中有多处引用，所以必须指定，不能删掉。但对于正文来说，仅用在首页顶部第一行大标题及信件环境结尾，不出现在其他位置。}
  \item {\color{awesome}\Verb{\dukangPDFTitle}用来生成PDF文件书签中的主标题，所以必须指定，不能删掉。}
}
\cventry[社交媒体信息部分][Awesome-CV][该部分用来定义社交媒体帐号或联系方式][部分可选]
{
  \item 该部分有若干社交媒体选项，可以根据需要进行定义，不需要的可以注释掉。
  \item 上面定义的分隔符\Verb{\acvHeaderSocialSep}就是用来分割这些帐号的。
  \item {\color{awesome}至少要保留一条，否则编译出错！}
}
\cventry[cvletter环境基本信息][Awesome-CV][cvletter环境一般用于定义首页的内容][必选]
{
  \item 由于使用了$ctex$宏包，\Verb{\today}默认为大写中文日期格式，比如{\today}。
  \item {\color{awesome}该部分的定义一个都不能少！}
}
\cventry[dukang导言区设定部分][\dk][此部分包含{\dk}及相关宏包提供的若干增强设定][必选]
{
  \item \Verb{\setbool{dukangParIndent}{true}}，由于Awesome-CV大多数风格都使用了组件化（自定义命令或环境）来实现，没有使用chapter/section等标准结构，这直接导致了在引入ctex宏包进行中文化的时候，需要对每个组件进行单独的设定，比如首行缩进两字符对于有些组件要么不起作用，要么显示错乱，这里提供一个全局开关，会自动根据组件的具体情况有选择的开启首行缩进，以达到风格统一、显示美观的效果。
  \item \Verb{\setbool{dukangBookmarkLeadingNumber}{true}}，Awesome-CV当前版本并不支持给输出的PDF文件按照文档结构自动添加书签（导航栏），{\dk}提供了这方面的支持，这个全局开关用来指定所添加的书签标题前，是否包含阿拉伯数字的章节编号。
  \item \Verb{\hypersetup}，该部分用来为生成的PDF文件提供若干属性字段。
}
\cventry
[Awesome-CV文档区设定部分]
[Awesome-CV]
[该部分设定出现在文档区，也就是\Verb{\begin{document}和\end{document}之间。}]
[可选]
{
  \item \Verb{\makecvheader[R]}，{\color{awesome}这不是页眉！Awesome-CV没有页眉。}这是首页包括Logo在内的抬头（Header）部分，可以注释掉，首页布局会自动从cvletter环境开始。可用选项用来控制对齐方向，L标识左对齐，C标识居中对齐，R标识右对齐。{\color{awesome}都要大写！}
  \item \Verb{\makecvfooter}，这个是每页的页脚，分为左中右三个部分，每个部分都可以留空，但{\color{awesome}必须保留大括号\Verb{{}}}
}
\end{cventries}

以上是{\dk}当前版本设定部分的详细说明，需要格外注意的地方都有颜色高亮，右边颜色高亮的标签说明该选项来自哪个部分。并且，假如在修改的过程中不小心把main.tex搞乱了也没关系，可以随时打开dukang-doc.tex查看正确的配置，或者干脆把除了正文以外的所有内容复制回来，重新设定一下，就又可以开始创作了。这也是为什么我推荐用\Verb{\input{...}}把文档正文章节和main.tex主文件分开的原因。

\begin{dkcomment}*[温馨提示]
  无论何时，dukang-doc.tex都是你值得参考的示例文档，文档本身和其内容章节文件（特别是源代码）尽量涵盖到了{\dk}的全部功能，包括设定和功能模块等，随时可以回来查看。\faKissWinkHeart
\end{dkcomment}

\cvsubsection{使用流程}
{\dk}的编译控制文件Makefile提供了适合下面几种场景的编译流程，相信总有一个适合你。首先，对于一般使用来说，需要做的步骤很简单：

\begin{center}
  \dkcodebox{修改main.tex}~\faArrowCircleRight~\dkcodebox{添加内容}~\faArrowCircleRight~\dkcodebox*{make}~\faCheckCircle
\end{center}

这样在src文件夹下就得到了main.pdf，同时在resource文件夹下，如果有符合命名规则的资源文件，也会被联动编译，并生成对应的PDF文件。{\dk}当前版本资源文件的命名规则是\dkbutton{r-*.tex}，符合这个规则的.tex文件都会被自动编译和控制。

如果想要保留编译之后的PDF，同时把项目目录清理干净的话：

\begin{center}
  \dkcodebox{修改main.tex}~\faArrowCircleRight~\dkcodebox{添加内容}~\faArrowCircleRight~\dkcodebox*{make}~\faArrowCircleRight~\dkcodebox*{make clean}~\faCheckCircle
\end{center}

最后，如果希望只保留源代码\footnote{比如用于提交源代码，归档，或者你就是个纯粹的代码强迫症患者{\color{awesome}\faHeart}}，把其他临时文件连同编译出来的东西一同干掉的话：

\begin{center}
  \dkcodebox{修改main.tex}~\faArrowCircleRight~\dkcodebox{添加内容}~\faArrowCircleRight~\dkcodebox*{make}~\faArrowCircleRight~\dkcodebox*{make cleanall}~\faCheckCircle
\end{center}

\begin{dkcomment}
  如果在编译过程中出现问题，强制退出编译过程之后想要再次编译，最好先执行\dkcodebox*{make cleanall}一遍，清理完所有临时文件之后再开始，否则编译很可能会出错无法继续下去。
\end{dkcomment}


\clearpage
